home *** CD-ROM | disk | FTP | other *** search
/ Turnbull China Bikeride / Turnbull China Bikeride - Disc 2.iso / STUTTGART / EDITORS / ZAP130 / !Zap / !Help < prev    next >
Text File  |  1995-06-20  |  64KB  |  1,468 lines
  1. *****************************************************************************
  2. * >!Help file for Zap version 1.30                        *
  3. * Copyright Dominic Symes 1992-1995. See 'Copyright' file.            *
  4. *****************************************************************************
  5.  
  6.                          ZAP is a text editor
  7.  
  8. Main features:    * Display may be in many different editing modes. Eg:
  9.           Text, byte, disassembly, coloured C, assembler, Basic.
  10.         * All key short cuts and menus are user redefinable.
  11.         * Full (unix style) wildcard search with your own definable
  12.           macros and search 'throwback' buffers.
  13.         * Proper unix tabs and true scrollbar operation.
  14.         * Full undo on all operations.
  15.         * Copy/End key causes standard cursor editing.
  16.         * Fast redraw in bitmap or anti-aliased fonts. Lots of
  17.           different bitmap fonts supplied.
  18.         * Any number of markers on each file, and a facility for
  19.           following branches in disassembly mode.
  20.         * Full ARMBE style BASIC Editor.
  21.         * Search as you type with minibuffer.
  22.         * Learns keys sequences.
  23.         * Emacs style Yank (Cut & Paste) and !Edit style move and
  24.           copy implemented.
  25.         * C throwback/info supported.
  26.         * Reads disc sectors/tracks and memory of other tasks.
  27.         * Keyboard selection of regions.
  28.         * Taskwindow supports control characters / line-editor.
  29.         * Emacs compatible keymap.
  30.         * Auto indent.
  31.         * Can edit assembler instructions when in code mode.
  32.         * Compatible with  Risc Os 2 & 3 & Risc PC.
  33.         * Automatic detection of DOS text files and Spool files.
  34.         * Uses dynamic areas on the Risc PC.
  35.  
  36. *************************************************************************
  37. * Important:                                *
  38. *************************************************************************
  39.  
  40. (1)    If you find this help file too technical, then please look in the
  41.     ZapPrimer directory (in the 3rdParty directory). This contains a
  42.     'beginners manual', aimed at those used to 'Edit'.
  43.     Thanks to David Holden for writing this.
  44.  
  45. (2)    This file does NOT contain help on the menu items and dialogue
  46.     boxes. See the Docs.Helpdata file or run the !Help application (in
  47.     Resources:Apps) to find out about these.
  48.     
  49. (3)    The 3rdParty extension modes each have their own help file in the
  50.     3rdParty directory.
  51.     
  52. (4)    If you are changing versions of Zap then please read the 'Changes'
  53.     file first!
  54.  
  55. *************************************************************************
  56. * Contents:                                                             *
  57. *************************************************************************
  58.  
  59.     Section A    Keys and options.
  60.             A.1 Summary of default key & mouse actions.
  61.             A.2 How to (re)define more keys.
  62.             A.3 How to change Zap's default options.
  63.             A.4 Differences RISCOS 2/3/3.5.
  64.             A.5 Multiple keymaps / the Emacs keymap.
  65.             A.6 Colour and changing the default colours.
  66.             
  67.     Section B    Loading/saving/printing/editing files
  68.             B.1 Loading files/creating files.
  69.             B.2 Saving files and ~ backups.
  70.             B.3 Dumping/printing files.
  71.             B.4 Selecting regions.
  72.             B.5 Copying/cutting/pasting/yanking.
  73.             B.6 Inserting text/control codes
  74.             
  75.     Section C    Editing BASIC - PLEASE READ
  76.             C.1 How to change editors/options.
  77.             C.2 Using BASIC in ARMBE mode.
  78.             C.3 Testing BASIC programs.
  79.             C.4 The cln_Backward error.
  80.             
  81.     Section D    Individual mode help.
  82.             D.0 Text mode
  83.             D.1 Byte mode .. etc ..
  84.             
  85.     Section E    Search and Replace.
  86.             E.1 The Search window.
  87.             E.2 The Replace window.
  88.             E.3 Keyboard (incremental) search.
  89.             
  90.     Section F    Other features.
  91.             F.1 Learning key sequences - very useful.
  92.             F.2 Tabs and indenting.
  93.             F.3 Fonts and font sizes.
  94.             F.4 Universal arguments.
  95.             F.5 The minibuffer
  96.             
  97.     Section G    How to find out more.
  98.             G.1 Other help files - MENU help.
  99.             G.2 Obtaining future versions of Zap.
  100.             G.3 Contacting me with suggestions/bugs.
  101.             
  102. *************************************************************************
  103. * Section A:    Keys and options.                    *
  104. *************************************************************************
  105.  
  106. A.1 Default key actions
  107. -----------------------
  108.  
  109. When Zap is loaded, it reads in the 'keys' file, and uses this to create the
  110. current key bindings. Many other options are also stored in this file. See
  111. section A.3 for more details. Each key mentioned in the 'keys' file has a
  112. command name following it. By editing the file and moving the command names
  113. about, you can change the action of any key. See section A.2 for more details
  114. (the format of a 'keys' file entry and how to define multiple keymaps).
  115.  
  116. Please note that the key short cuts given in the menus are automatically
  117. updated to reflect your new choice of keys (for whatever you have set as the
  118. default keymap). A summary of the default key bindings is given below.
  119. (s=Shift c=Ctrl sc=Shift+Ctrl).
  120.  
  121. Key:        Command:    Action:
  122.  
  123. Return        RETURN        Splits line / inserts new line in line edit
  124.                 mode. Also indents in auto-indent mode.
  125.                 Edits an instruction in code mode.
  126. sReturn        RETURN        As above.
  127. cReturn        RETURNNOINDENT    As RETURN except doesn't auto-indent.
  128.  
  129. Delete        DELETE        Delete last character.
  130. sDelete        DELETENEXT    Delete next character.
  131. cDelete        DELLINE        Delete current line.
  132. scDelete    DELTOEND    Delete to end of line.
  133.  
  134. Tab        TAB        Inserts a variety of tabs - see tab menu.
  135. sTab        SWITCHTAB    Switches between Unix and !Edit tab modes.
  136. cTab        -        Reserved for !Larger/!Menon users.
  137.  
  138. Escape           ESCAPE        Stops copy modes/selection modes/search
  139.                 as you type mode/yank mode.
  140. sEscape           CANCEL        Cancel operation and return to start posn.
  141. cEscape        COMMAND        Brings up a minibuffer in which you can type
  142.                 any Zap command. Equivalent of Emacs M-X.
  143.                 
  144. <-|        DELETE        Delete last character.
  145. s<-|        DELETE        Delete last character.
  146. c<-|        FASTUNDO    Undo last operation.
  147. sc<-|        LASTMARK    Jump to last marker
  148.  
  149. Copy        COPY        Initiates split cursor copying. Move cursor
  150.                 with cursor keys and use COPY key to copy.
  151.                 Note that you may copy from one window to
  152.                 another by pressing SELECT on the other.
  153. sCopy        COPY        For those who wish to redefine Copy to be
  154.                 DELETENEXT. Copy key still ok in copy mode.
  155. cCopy        SELREGION    Starts selection of a region via cursor keys.
  156.                 Press Escape/cCopy to end the selection.
  157. scCopy        DUMPFILE    Produce text version of the display.
  158.  
  159. Insert        TOGGLEINSERT    Toggle insert and overwrite modes.
  160.  
  161. Print        QUICKPRINT    Send file directly to printer.
  162. sPrint        PRINTFILE    Print file through printer driver.
  163. cPrint        OPENPRINTER    Open 'printer:$' filer window.
  164. scPrint        CLOSEPRINTER    Close 'printer:$' filer window.
  165.  
  166. Space bar    CHAR &20    Inserts a space.
  167. sSpace        CHAR &20    As above.
  168. cSpace        SELREGION    Emacs compatible.
  169. scSpace        UNSPACE        Remove excess spacing around the cursor.
  170.  
  171. Cursor keys:
  172.  
  173. Left            LEFT        Moves 1 left / goto last mark in code mode.
  174. Right        RIGHT        Moves 1 right / goto address in code mode.
  175. Down        DOWN        Move 1 line down.
  176. Up        UP        Move 1 line up.
  177. sLeft          SLEFT        Move back one word.
  178. sRight        SRIGHT        Move forward one word.
  179. sDown/PageDown    SDOWN        Move down a page.
  180. sUp/PageUp        SUP        Move up a page.
  181. cLeft        CLEFT        Move to start of logical line.
  182. cRight        CRIGHT        Move to end of logical line.
  183. cDown        CDOWN        Move to end of text (and leave marker).
  184. cUp        CUP        Move to start of text (and leave marker).
  185. scLeft        SCLEFT        Move to the left without moving cursor.
  186. scRight        SCRIGHT        Move to the right without moving cursor.
  187. scDown        SCDOWN        Move down without moving cursor.
  188. scUp        SCUP        Move up without moving cursor.
  189.  
  190. Function keys:
  191.  
  192. F1        EXECUTE        Execute learnt key sequence (see F.1).
  193. F2        FINDFILE    Load a named file (Emacs C-X C-F).
  194. F3        SAVE        Brings up save box. See save box help.
  195. F4        SEARCHCUR    Brings up Search to cursor box. (See E.1).
  196. F5         GOTO        Brings up Goto line/address box.
  197. F6         TOGGLEMARK    Inserts marker in text/deletes marker.
  198. F7        SEARCHBUF    Brings up Search to buffer box. (See E.1)
  199. F8        FULLUNDO    Full undo (takes longest path in undo tree).
  200. F9        REDO        Redo (undo last undo whether full or fast).
  201. F10        DELLINE        Delete current line.
  202.  
  203. sF1        SPLITLINE    Split line (useful in Basic mode).
  204. sF2        SWAPWINDOW    Swap window (to next window/last used).
  205. sF3        HEXASCII    Toggles hex entry mode when byte/word modes.
  206. sF4        REPLACE        Brings up search and replace box. (See E.2).
  207. sF5        NULL        Reserved.
  208. sF6        LASTMARK    Last mark (eg after ctrl-down by mistake).
  209. sF7        NEXTMATCH    Next match (after an F4 or F7 search).
  210. sF8        RENUMBER    Renumbers a BASIC file.
  211. sF9        NEXTMARK    Jump to next set marker.
  212. sF10        DELTOSTART    Delete to start of line.
  213.  
  214. cF1        JOINLINE    Join line (useful in Basic mode).
  215. cF2        CLOSEWINDOW    Close current window (and jump to next).
  216. cF3        QUICKSAVE    Save the file with no prompt.
  217. cF4        NEWVIEW        New view (open new window on this file).
  218. cF5        WORDWRAP    Toggle wordwrap mode (w in title).
  219. cF6        FORMATTEXT    Format text to start of next paragraph.
  220. cF7        LASTMATCH    Previous match (see sF7).
  221. cF8        BINDTOKEY    Bind the learnt sequence (see cL) to a key.
  222. cF9        SAVESEL        Open the 'save selection' window.
  223. cF10        DELTOEND    Delete to end of line (emacs style ctrl K).
  224.  
  225. scF1        MODEN "Text"    Text mode   (display in text format)
  226. scF2        MODEN "Byte"    Byte mode   (display in hex bytes)
  227. scF3        MODEN "Word"    Word mode   (display in hex words)
  228. scF4        MODEN "Ascii"    Ascii mode  (display in characters)
  229. scF5        MODEN "Code"    Code mode   (display in disassembled code)
  230. scF6        MODEN "Basic"    BASIC mode  (display tokenised Basic)
  231. scF7        MODEN "Bastxt"    BASTXT mode (display detokenised Basic)
  232. scF8        MODEN "Softwrap" Softwrap mode - soft line endings.
  233. scF9        MODEN "C"    Colour C mode.
  234. scF10        MODEN "Assembler" Colour Acorn assembler mode.
  235.  
  236. Ctrl letters:
  237.  
  238. cA        CLEFT        Start of line    (emacs compatible)
  239. cB        LEFT        Back a character (emacs compatible)
  240. cC         COPYSEL        Copy selected region to current position.
  241. cD        DELETENEXT    Delete next char (emacs compatible)
  242. cE        CRIGHT        Go to line end     (emacs compatible)
  243. cF        RIGHT        Forward a char   (emacs compatible)
  244. cG        CANCEL        Cancel search 'as you type' and return to
  245.                 start. Also cancel any yank operations.
  246.                 Escape from minibuffer. (emacs compatible)
  247. cH        HELP        Get help on Zap, a key, Zap command or mode.
  248. cI        INDIRECT    Indirect (move to the address given by word
  249.                 at cursor - useful in Code mode).
  250. cJ        INDENT        Indent selection by string (see selection
  251.                 menu).
  252. cK        DELTOEND    Kill line     (emacs compatible)
  253. cL        LEARN        Learn key sequence (see F.1).
  254. cM        RETURN        Performs return action for current mode.
  255. cN        DOWN        Next line     (emacs compatible)
  256. cO        TOFRONT        Bring editor window to front of windows.
  257. cP        UP        Previous line     (emacs compatible)
  258. cQ        QUOTE        Insert next character into text (even if it
  259.                 is a ctrl character. eg cQ,cA inserts #1).
  260. cR        SEARCHBACK    Reverse search 'as you type'.
  261. cS        SEARCHFORWARD    Search 'as you type' forwards.
  262. cT        SELECTBUFFER    Select entire buffer.
  263. cU        UNIVERSALARG    Perform next instruction 'n' times. Eg
  264.                 cU 4 RETURN A inserts 4 A's.
  265. cV        MOVESEL        Move selected region to current position.
  266. cW        SETWIDTH    Set the window width.
  267. cX        CUT        Delete/Cut selected region.
  268. cY        PASTE        Paste/Yank once selected region.
  269. cZ        CLEARSEL    Clear selection.
  270. c[        OSCLI        Execute an operating system * command.
  271.  
  272. scA        LINENOS 3    Addresses shown at line start.
  273. scB        BASIC        Drop into Basic with program downloaded.
  274. scC        COMPILE        Saves then chains/compiles a program.
  275. scD        INSERTDATE    Insert current date (format in 'keys' file).
  276. scE        SAVEANDRUN    Saves then runs a program then exits.
  277. scF        RUNANDQUIT    Runs a program and then exits.
  278. scG        TOGGLEWIND    Toggle window size.
  279. scH        LISTFNS        List function definitions.
  280. scI        NEXTTRACK    Move forward one track.
  281. scJ        LASTSECTOR    Move back one sector.
  282. scK        NEXTSECTOR    Move forward one sector.
  283. scL        LINENOS 1    Logical line numbers shown at line start.
  284. scM        LASTTRACK    Move back one track.
  285. scN        NOLINENOS    Removes line numbers/addresses.
  286. scO        TOGGLEHEX    Line numbers shown in hex/decimal.
  287. scP        PHYSICAL    Physical line numbers shown at line start.
  288. scQ        SWAPCHARS    Swap next two characters around.
  289. scR        READONLY    Toggle read only state (r in title).
  290. scS        SWAPCASE    Swap case of next character/selected region.
  291. scT        INSERTTIME    Insert current time (format in 'Keys' file).
  292. scU        RUN        Run a basic program from memory.
  293. scV        -        Reserved.
  294. scW        KEEPREGION    Put selected region into yank buffer.
  295. scX        CLOSEOTHER    Close other open window.
  296. scY        YANK        Yank cyclically through deleted regions.
  297. scZ        KEYMAP 1    Emacs prefix key (eg scZ ESC X).
  298. sc- (c_)    FULLUNDO    Undo (emacs compatible)
  299.  
  300. Standard mouse actions:
  301.  
  302. Click SELECT:    Place cursor at the clicked position.
  303. Click MENU  :    Bring up the window menu.
  304. Click ADJUST:    1. If the window contains a selection then it is resized.
  305.         2. If the window contains a cursor then a selection is
  306.            formed between the cursor and the click position.
  307.         3. The cursor is moved to the last used position (the hollow
  308.            square if neither of the above apply).
  309.  
  310. Drag SELECT:    Selects a new region.
  311. Drag ADJUST:    Resizes the current region.
  312.         (in either case holding down CTRL leaves the cursor unmoved).
  313.  
  314. Double click SELECT:    Select a word.
  315. Treble click SELECT:    Select a line.
  316. Quadruple    SELECT:    Select a paragraph.
  317. Quintruple   SELECT:    Select the whole text.
  318.  
  319. A.2 How to redefine more keys
  320. -----------------------------
  321.  
  322. At the start of the 'keys' file, the keys for keymap 0 (the default key map)
  323. are defined. Each line is of the form "comment &xxx command" where 'comment'
  324. is any text without a '&' describing the key, 'xxx' is the number of the key
  325. in hexadecimal (Zap key number - see below), ' ' is any number of spaces and
  326. tabs, and 'command' is the command (or list of commands) to be attached to
  327. that key. You may edit the file to add/remove keys as you please.  If a key
  328. is not mentioned in the keys file then it is passed on to the next task. Thus
  329. DO NOT put F12 in the 'keys' file (or if you do then bind it to the command
  330. SUSPEND :-).
  331.  
  332. A list of the valid commands you can use and their actions is given in the
  333. file 'HelpData' within the 'Docs' directory. See also the file 'Commands' for
  334. the syntax to use. To summarise these details, string parameters must be in
  335. double quotes (or omitted if you wish the minibuffer to be opened), and
  336. commands can be strung together with the ':' separator (as in BASIC).
  337.  
  338. The Zap key numbers lie in the range &000-&1FF and are based on those
  339. returned by Wimp_Poll. Thus, the function keys return &180-&1FF, as
  340. documented in the PRMs. Just look at the 'keys' file if you don't have a copy
  341. of the PRMs. Standard characters return their ascii value &20-&FF as usual.
  342. &7F stands for unshifted DELETE. Internally Zap uses some extra codes in the
  343. range &00-&1F and &100-&17F which differ from the Wimp's. These are
  344. documented in the file E-Keycodes in the docs directory.
  345.  
  346. Example: Suppose you wished ctrl-] to enter the code &1D into the file. Then
  347. you would enter the line: "c]        &12D CHAR &1D".
  348.  
  349. The keys c0-c9 and sc0-sc9 have been left intentionally blank. I suggest
  350. these are used for user commands/macros or binding the learnt sequence to via
  351. cF8. See the section A.5 on how to define multiple keymaps and switch between
  352. them.
  353.  
  354. A.3 Changing the default options
  355. --------------------------------
  356.  
  357. The Zap menu you get when you click the MENU button on a window contains the
  358. status for that window only. Any options changed on this menu will be lost
  359. immediately the window is closed. To change any option permanently, use the
  360. 'options' menu obtained by clicking on the Zap icon on the iconbar. After you
  361. have changed the option on this menu click the 'save options' entry.
  362.  
  363. Alternatively, set up a window the way you like it and then use the 'Copy
  364. ops' menu option on the misc menu to make these options default. This doesn't
  365. work with some 3rd party mode specific options so you should use the options
  366. menu instead in this case.
  367.  
  368. Please note that some options are stored MODE dependantly. To change these
  369. options it is first necessary to SWITCH TO THE MODE WHOSE OPTIONS YOU WANT TO
  370. CHANGE ON THE OPTIONS.MODE MENU. The options you need to do this for include:
  371.     1) Display width.
  372.     2) Line number status.
  373.     3) Auto indent status.
  374.     4) Line edit/Non standard edit status.
  375.     5) Hex entry and Overwrite status.
  376.     6) Tab display status.
  377.     7) Colours.
  378.     8) Automatic space stripping on saving.
  379.     9) Tab insert status.
  380.     10) Auto-width status.
  381.     
  382. When you change mode, the other options menus will be updated to give the
  383. status of the flags for this mode.
  384.     
  385. Example: To turn the line numbers off in Basic editing mode use the sequence
  386. of clicks:
  387.  
  388.     zap.options.mode.basic
  389.     zap.options.display.linenumbers.none
  390.     zap.options.mode.text
  391.     
  392. The mode set on the 'Options.Mode' menu will also be the mode used for
  393. loading files whose type is not recognised, or when you hold down the CTRL
  394. key. In general you should always put this mode back to TEXT after changing
  395. options of other modes.
  396.  
  397. Other options that are saved by clicking Save Settings include:
  398.     1) Whether searches are case sensitive or not.
  399.        (and other options in the Search box)
  400.     2) Whether quick print adds a title header or not.
  401.     
  402. To change the size of an opened window for mode n, create a template in the
  403. current template file (see the !Run file to see which one is loaded) called
  404. mode_n. The size and position of this template determines the opening size
  405. and position (modulo stacking) of your window. The other template flags are
  406. not looked at.
  407.  
  408. Some other options are stored in the 'keys' file. The file entries are in the
  409. form: "<comment> &xxx <arg1> <arg2> ... <argn>" where 'xxx' is a number I
  410. will call the key variable number. The variable numbers in the keys file are
  411. documented below:
  412.  
  413.  &000-&1FF    The default keymap.
  414.          arg1=the command attached to that key code.
  415.  
  416.  &200-&20F    These give the 16 search macros.
  417.          arg1=the macro string (up to 3 chars)
  418.          arg2=the replacement string.
  419.  &300        The date format to use for scD.
  420.          arg1=format string as used by the SWI OS_ConvertDateAndTime
  421.  &301        The time format to use for scT.
  422.          arg1=format string as used by the SWI OS_ConvertDateAndTime
  423.  &302        The default font name to use in font display modes.
  424.  &303        The number of blank lines to leave at the end of a window.
  425.  &304        The default font size in points.
  426.  &305        The number of pixels to shave off the top of a font char.
  427.  &306        The number of pixels to shave off the bottom of a font char.
  428.  &307        The codes to send to the printer at the end of a line for
  429.          'quick print'. arg1=string to be GS transed.
  430.  &308        Number of characters to keep cursor from the left margin.
  431.  &309        Number of characters to keep cursor from the right margin.
  432.  &30A        Number of characters to keep cursor from the top.
  433.  &30B        Number of characters to keep cursor from the bottom.
  434.  &30D        Right hand margin in pixels.
  435.  &30E        Filetype of file to be created when SELECT clicked on
  436.          the iconbar.
  437.  &30F        Filetype of file to be created when ADJUST clicked on
  438.          the iconbar.
  439.  &310        The number of pixels to shave off the left of a font char.
  440.  &311        The number of pixels to shave off the right of a font char.
  441.  &314        The minibuffer size in characters.
  442.  &315        The default indent string.
  443.  &316        Flashing cursor on period in centiseconds.
  444.  &317        Flashing cursor off period in centiseconds.
  445.  &318        Minimum auto-width width
  446.  &319        Maximum auto-width width.
  447.  &31A        Name of the Zap font to use in low-res modes.
  448.  &31B        Name of the Zap font to use in hi-res modes.
  449.  
  450.  &400        The number of the default key map (usually 0).
  451.  &4xx (xx<>0)    Range of keymap xx (see A.5)
  452.          arg1=smallest Zap keynumber to be supported
  453.          arg2=largest Zap keynumber to be supported (inclusive)
  454.          
  455.  &5xx        These say which mode to load a file on dependent on the path.
  456.          arg1=filetype to match (-1 for match any)
  457.         arg2=filename to match - the string can contain any of
  458.              the wildcards documented under searching.
  459.         arg3=[+]<mode name> as for arg1 in the 1xxx's below.
  460.         NB The order in which the names appear is important - the
  461.         first match will be taken.
  462.  
  463.  &1xxx        These specify which of the Zap modes a file of filetype xxx
  464.          should be loaded in as (when CTRL not pressed).
  465.          arg1=[+]<mode name>
  466.          If the optional '+' is present then the file will be loaded
  467.          even if SHIFT is not held when you double click.
  468.          The mode name is CASE SENSITIVE.
  469.          Place the &1xxx variable before the &5xx ones if you want
  470.          the filetype to be checked before the pathname.
  471.          
  472.  &2000        As for &1xxx, but the mode to use for UNTYPED files.
  473.  
  474.  &10000+    These specify alternate keymaps (see A.5).
  475.  &y0xxx        arg1=the command to be mapped to key with code &xxx in
  476.          keymap number &y.
  477.  
  478. A.4 Differences with RISCOS 2/3/3.5
  479. -----------------------------------
  480.  
  481. DYNAMIC AREAS: Zap uses dynamic area storage for files and fonts on RO3.5. It
  482. uses the wimpslot in earlier versions of the OS.
  483.  
  484. FONTS: If using fonts on RO2, then Zap will need the outline font manager vsn
  485. 2.42. This is used by Impression and other DTP programs.
  486.  
  487. TASKWINDOWS: If using task windows, on RO2 then Zap will expect to find the
  488. module 'Task' in the System:Modules directory. This should be the Task module
  489. supplied with DDE. Of course ^F12 will not bring up the taskwindow on Risc Os
  490. 2. I'm sorry about this, but it's a lot of hassle for me to find a Risc Os 2
  491. machine to work on. You can always map ^F12 to the command TASKWINDOW.
  492.  
  493. LOADING FILES: Only left shift double click will load a non text file in RO2.
  494. Right shift is deliberately not tested for as some people use it for other
  495. things. I have no control over this on Risc Os 3.
  496.  
  497. HELP: There is no interactive menu help in RO2. You will have to read the
  498. HelpData file directly.
  499.  
  500. A.5 Multiple keymaps / the Emacs keymap.
  501. ----------------------------------------
  502.  
  503. Zap can support several keymaps at once. Each keymap is numbered 0-255.
  504. In the default 'keys' file, keymap 0 is the standard Zap keymap and keymap 1
  505. an Emacs emulation keymap. Keymaps 2-4 form part of the Emacs keymap as I
  506. will describe below. To switch to keymap n, use the command "BASEMAP n" (by
  507. pressing Ctrl-Escape or binding the command to a key). The commands
  508. DEFAULTMAP and EMACS act as BASEMAP 0 and BASEMAP 1 respectively.
  509.  
  510. The default keymap to use when Zap starts up is given by variable number &400
  511. in the keys file. Set this to 1 if you wish to use the Emacs keymap all the
  512. time.
  513.  
  514. To define a new keymap, keymap number &yy say, you need to do two things.
  515. First you must enter a line in the 'keys' file reserving space for the keys.
  516. This takes the form:
  517.  
  518.     &4yy    &aa    &bb
  519.     
  520. where &aa is the smallest keynumber you wish to use and &bb the largest
  521. (inclusive). See entry &401 for an example.
  522.  
  523. Next you must define the keys. To define key number &xxx you must enter a
  524. line in the 'keys' file of the form:
  525.  
  526.     &yy0xxx        <command>
  527.     
  528. where <command> is the name of the command to be attached to the key. The
  529. format of the <command> field is described in A.1 and the 'Commands' file.
  530.  
  531. By using multiple keymaps you can provide for a sequence of keys to execute a
  532. command. To do this you need the 'KEYMAP' command. The command 'KEYMAP n'
  533. switches the current keymap to 'n'. However, after the next key has been
  534. read, the current keymap is restored to whatever basemap you have set with
  535. the basemap command. Thus in effect, the keymap only changes for the next
  536. keypress (unless that two has a KEYMAP command).
  537.  
  538. For example, in Emacs "Ctrl-X 4 F" loads a file. This is accomplished by
  539. setting:
  540.  
  541.     Ctrl-X in keymap 1 is bound to     KEYMAP 2
  542.     4 in keymap 2 is bound to     KEYMAP 4
  543.     F in keymap 4 is bound to     FINDFILE
  544.  
  545. After the command FINDFILE has been executed, the keymap will be restored to
  546. 1 for the next key press.
  547.  
  548. A.6 Colour
  549. ----------
  550.  
  551. Colour is changed using the 'Colour' menu off the 'Display' menu, both on
  552. the main Zap window menu. The first 9 colours you can change are the same
  553. for all modes, being:
  554.  
  555. Colour    Action
  556.  
  557. 0    Background1    The colour used for squares containing no text.
  558. 1    Background2    The colour used for squares containing text.
  559. 2    Foreground    The standard foreground colour.
  560. 3    Selection-B    Selection background colour.
  561. 4    Selection-F    Selection foreground colour.
  562. 5    Cursor-Bac    Cursor background colour (ie the cursor colour).
  563. 6    Cursor-For    Cursor foreground colour.
  564. 7    Line nums    Colour used for line numbers (eg in Basic mode).
  565. 8    Ctrl chars    Colour used for control characters (0-31).
  566.  
  567. Colours 9+ are mode dependant and lie below a dotted line. If the 'all modes'
  568. flag at the top of the menu is set then when you change one of the colours
  569. 0-8 (as above) then it is changed for all modes, not just that one mode.
  570. Colours 9+ only set the colour for that mode regardless of the status of this
  571. flag. You will need to change modes to set up the colours for different modes
  572. differently.
  573.  
  574. Of course, if you change colours from the window menu, then the colours are
  575. only changed for that window and are lost when the window is closed. To
  576. change them permanently, use the Display menu off the options menu and then
  577. click on 'save options' (or use the Copy Ops menu option).
  578.  
  579. *************************************************************************
  580. * Section B:    Loading,Saving,Printing,Editing files            *
  581. *************************************************************************
  582.  
  583. B.1 Loading/creating files
  584. --------------------------
  585.  
  586. These are the ways to load a file into Zap:
  587.  (a) If the file is a text file then double click on it.
  588.      (or more generally if there is a '+' for this type in the keys file).
  589.  (b) If the file is typed then hold down left shift and double click on it.
  590.  (c) If the file is untyped then drag it onto the Zap icon on the iconbar.
  591.  (d) Press F2 then type the name of the file and RETURN (TAB completes the
  592.      filename).
  593.  
  594. When you load a file into Zap, it works out the best mode to load it into. At
  595. the moment there are two mechanisms for doing this, both specified in the
  596. 'keys' file. These are: (see A.3 for more details).
  597.  
  598. (i) By filename: The keys variables &5xx are followed by a filetype then a
  599.     filename and then a mode to use. If the (wildcarded) filename matches
  600.     and the filetype matches then that mode is used.
  601.     
  602. (ii) By filetype: The keys variable &1xxx is followed by the mode name to
  603.      use for type &xxx. If the name is preceded by a '+' then the file is
  604.      loaded even if shift is not held.
  605.      
  606. If the file satisfies more than one of the above criterion, then the first
  607. one mentioned in the keys file will be used.
  608.  
  609. Sometimes you may wish to load a file in a mode other than its default one.
  610. To do this, set the required mode on the 'Options.Mode' menu, and then hold
  611. down the CTRL key while loading the file. (Eg Shift-Ctrl double click on the
  612. file). It will then be loaded in the selected mode (usually text).
  613.  
  614. Dragging a file into an open window inserts the data at the current cursor
  615. position. RAM loads/saves are fully supported and you may even save a file
  616. into itself. If you are short of memory then I suggest you switch the undo
  617. buffer off before performing such drags. (Use the File menu).
  618.  
  619. In any mode the window title is of the form:
  620.  
  621.  "<filename> [*] ([mode name] [options]) [view number/number of views]".
  622.  
  623. The title is centered unless the window is small when it is right aligned so
  624. you can see the leaf name and options of the file. A '*' indicates that the
  625. file has been altered since last saved. The options characters are described
  626. below. The view number is only shown if you have more than one view on a
  627. file.
  628.  
  629.  R        Read only and fixed as read only.
  630.  r        Read only but can be toggled to read/write by scR.
  631.  u        Undo supported by this file (so cX acts as cut, not delete).
  632.  o        Overwrite mode active (toggle via Insert key).
  633.  h        Hex entry mode active for Byte/Word (toggle via F2).
  634.  w        Wordwrap mode active (toggle via cF5).
  635.  l        Line edit mode active (return inserts new line).
  636.  a        Auto indent mode active (see the Edit submenu).
  637.  n        Non standard mode active (used by ARMBE emulation mode).
  638.  L        Line wrap mode.
  639.  D        This is a DOS text file (LF->CRLF on saving)
  640.  S        This is a Spool text file (LF->LFCR on saving)
  641.  
  642. You may also create files of a given type using the 'Create.Type' menu, or
  643. grab modules using the 'Create.Getmodule' menu. Zap can also read disc
  644. sectors and other applications memory. Click SELECT on the Zap icon to create
  645. a new text file and ADJUST on the Zap icon to create a new BASIC file. You
  646. can change the type of file created by SELECT/ADJUST click in the 'keys'
  647. file.
  648.  
  649. Zap will warn you before overwriting a file of the same name if it is
  650. altered. If it is unaltered then the newly loaded file will replace the one
  651. currently loaded as in !Edit.
  652.  
  653. When a file is loaded, OS_FSControl, Canonicalise_Path will be called to
  654. convert any path references into full path names (unless you have RISC OS 2).
  655.  
  656. B.2 Saving files and ~ backups
  657. ------------------------------
  658.  
  659. Press F3 (or click on the menu option 'File') to open the save box. You may
  660. change the file type either by clicking the MENU button, or by moving to the
  661. type name window, typing the new type name and pressing RETURN. Zap will warn
  662. you if you are about to overwrite a more recent file (if you have the
  663. check-dates option on - see the options.misc menu), or if the file contains
  664. no path. If you ignore the warning then it will save the file to the
  665. currently selected directory.
  666.  
  667. Ctrl-F3 (or clicking on 'File.Save') does a direct save. Ctrl-F2 deletes the
  668. current file and Shift-Ctrl-X deletes the other file being viewed. Please
  669. note that when the SAVE,DISCARD,CANCEL box pops up you may simply press
  670. 'S','D',or 'C' instead of using the mouse. The same holds for other dialogue
  671. boxes (ctrl S,D,C are also valid).
  672.  
  673. If the directory in which the file is saved contains a directory called ~ or
  674. ~<num> where <num> is any number then instead of the file simply being
  675. overwritten, the old version is moved into the ~ directory. If you have
  676. multiple ~ directories - eg ~1,~2,~3 ... ~n then the last n versions of the
  677. file are kept.
  678.  
  679. If you are using one of the basic modes then please note that you must save
  680. from a window in the correct mode. If you switch to text mode and then save,
  681. your file will be saved as a text file and not a Basic program.
  682.  
  683. B.3 Dumping, printing files
  684. ---------------------------
  685.  
  686. First note that any window display may be turned into a text file simply by
  687. pressing SHIFT-CTRL-COPY. Once you have done this you could print a file
  688. simply by saving it to a printer driver, or by opening the 'printer:$' filing
  689. system (press ctrl-print) and saving the file into it. Zap also provides two
  690. other printout commands.
  691.  
  692. The first, 'quick print' can be got by pressing the 'Print' key. When you
  693. press Return, or click 'PRINT', it will send the display to the printer
  694. directly. It sends a LF and a CR to the printer at the end of each line. You
  695. may configure the codes sent by altering the 'keys' file variable &307.
  696.  
  697. The second, 'fancy print' can be got by pressing 'Shift-Print'. You must have
  698. a printer driver loaded. The file will then be output via the printer driver
  699. in the current outline font selected via the 'Display.Font.Othername' menu.
  700. This option still has problems - especially with Computer Concepts Turbo
  701. drivers. It is probably better to save the file onto the printer driver
  702. directly.
  703.  
  704. B.4 Selecting regions
  705. ---------------------
  706.  
  707. There are several ways to mark regions in Zap. The most obvious is to use the
  708. mouse.
  709.  
  710. If there is no region selected then DRAG SELECT will mark a new region, and
  711. ADJUST CLICK/DRAG will select between the clicked point and the cursor. If
  712. there is already a region selected then DRAG SELECT will start selecting a
  713. new region, ADJUST CLICK/DRAG will alter the old region. In either case, hold
  714. down the CTRL key to leave the cursor unaffected by the selection.
  715.  
  716. The second method is to use the keyboard. This method is much faster when
  717. you have got used to it. First move to the start of the region you wish to
  718. mark. Then press CTRL-COPY and move (via the cursor keys) to the end of the
  719. region. Then press ESCAPE (or CTRL-COPY).
  720.  
  721. The third method is to use multiple clicks. Double click marks a word, triple
  722. click a line, quadruple click a paragraph and quintuple click the whole
  723. file. If you do a drag selection after the second/third click, then the text
  724. will be selected in words/lines. Note that the BASIC mode limits selected
  725. regions across lines to full Basic lines (like the ARMBE).
  726.  
  727. B.5 Copying/pasting/cutting/yanking
  728. -----------------------------------
  729.  
  730. Zap implements both the !Edit style copy/move and the Emacs style paste/yank.
  731.  
  732. The !Edit method: To move a region to the cursor position press ctrl-V. To
  733. copy a region press ctrl-C.
  734.  
  735. The Emacs method: To move a region cut it with ctrl-X and then paste it with
  736. ctrl-Y (the undo buffer must be on to do this). To copy a region, grab it
  737. with shift-ctrl-W (Emacs meta-W) and paste it with ctrl-Y. Press shift-ctrl-Y
  738. (Emacs meta-Y) to cycle through the previously deleted regions. Also note
  739. that multiple presses of ctrl-K or F10 produce data which can be yanked by
  740. ctrl-Y.
  741.  
  742. Another way to copy text is via the COPY key. This is faster for copying
  743. small sections of other lines. First press the COPY key to split the cursor
  744. into two. One cursor can be moved about by the cursor keys. Move this to the
  745. area you wish to copy from and press the COPY key once for each character.
  746. Press ESCAPE or RETURN to cancel the copy mode. Please note that you can also
  747. use this method across windows and even across modes!
  748.  
  749. B.6 Inserting text/control codes
  750. --------------------------------
  751.  
  752. In text mode there are two features to help you format text as you type it.
  753. The first is called 'word wrap' and is toggled on and off via cF5. The second
  754. is called 'line wrap' and can be toggled on and off via the 'Edit' menu (or
  755. you can bind the LINEWRAP command to a key if you wish). Whilst either of
  756. these modes are active, text typed beyond the 'wrap width' margin (set via
  757. the 'Edit' menu) is automatically split at spaces and placed on the next
  758. line. 'Wordwrap' differs from 'linewrap' in that when you delete characters,
  759. the paragraph will be formatted in wordwrap mode (thus pulling text back) but
  760. not in linewrap mode.
  761.  
  762. There are two ways to insert control characters. The first is to 'quote' the
  763. character. To do this, press ctrl-Q and then type the control character you
  764. want to insert. Eg, ctrl-Q ctrl-A will insert the byte 1. The second is to
  765. switch to byte mode (scF2), type the digits in hex and then switch back to
  766. text mode (scF1). This assumes that 'hex entry mode' is active in byte mode.
  767.  
  768. When creating macros, by binding a list of commands to a key, you may find
  769. the commands INSERT and INSERTGS useful. The first inserts a string into the
  770. text and the second GS-Trans's it first.
  771.  
  772. *************************************************************************
  773. * Section C:    Editing BASIC - PLEASE READ                *
  774. *************************************************************************
  775.  
  776. C.1 Changing editors/options
  777. ----------------------------
  778.  
  779. There are essentially 3 ways to edit basic programs in Zap. Do not be put off
  780. if you dislike the default configuration. You may change most things to your
  781. preference.
  782.  
  783. In the default configuration, basic programs are edited in the Zap extension
  784. mode called BASIC. This is designed to be a desktop version of Acorn's ARMBE.
  785. Those people used to ARMBE should find this mode very easy to use. The
  786. program is edited while tokenised and line numbers are shown in the margin
  787. and updated when new lines are inserted.
  788.  
  789. Return and delete act differently from ARMBE, acting as they do for the
  790. standard text mode (this is called stream editing). If you wish them to act
  791. precisely as in ARMBE then switch on the 'lineedit' and 'nonstandard'
  792. options. They will then act in a 'line editor' fashion with Return inserting
  793. a new line rather than splitting the current one. The functions Split and
  794. Join (sF1 and cF1) can then be used to split/join lines.
  795.  
  796. For those people who wish to edit BASIC in tokenised form, and thus with line
  797. numbers accessible, but don't want to see them in the margin, they can be
  798. switched off. Perform the option changes indicated by the clicks:
  799.  
  800.     options.mode.BASIC         ; configure basic mode
  801.     options.display.linenumbers.none ; turn off line numbers
  802.     options.mode.TEXT         ; return config mode to text
  803.     options.save options         ; save your Config file
  804.     
  805. For those who prefer to edit basic in detokenised form, there is a separate
  806. mode named BASTXT which accomplishes this. To load a single file in using
  807. this mode it is easiest to set the options menu mode to BASTXT and hold down
  808. CTRL key while loading the file. To change to the BASTXT mode permanently,
  809. change the line of the 'Keys' file which reads:
  810.  
  811.     Basic        &1FFB    BASIC
  812.     
  813. to read:
  814.  
  815.     Basic        &1FFB    BASTXT
  816.     
  817. In this mode, whenever a file is loaded it is converted into text with line
  818. numbers striped. Saving is the converse. Please note that if the program
  819. contained line number references, then Zap will beep before forcing the BASIC
  820. mode described in C.2.
  821.  
  822. C.2 Using BASIC in ARMBE mode
  823. -----------------------------
  824.  
  825. In it's default setup the BASIC mode is designed to emulate ARMBE. Thus line
  826. numbers are displayed in the left margin, and automatic renumbering takes
  827. place as lines are added to the file. All GOTO and GOSUB line number
  828. references are automatically updated.
  829.  
  830. In line editor mode, the RETURN key inserts a new logical line. To split the
  831. line in two at the current cursor position press SHIFT-F1 and to join two
  832. lines press CTRL-F1. When two lines are joined, a ':' is inserted between the
  833. statements. If you do not like this, it can be switched off by turning off
  834. the line-edit and non-standard flags on the edit menu. See above.
  835.  
  836. Text is typed as usual with the proviso that tokens are automatically
  837. expanded. For example 'P.' will be expanded to 'PRINT' when you press the
  838. dot. Also note that in non-standard editing mode excess spaces are
  839. automatically removed from the end of a line (except when this would prevent
  840. the line wrapping onto the next). 'Unix' tab mode just advances the cursor to
  841. the next tab stop as in ARMBE. The other tab modes, !Edit and Coltab work as
  842. in the text mode.
  843.  
  844. Copying bits out of the middle of lines is performed using the COPY key.
  845. Groups of lines are selected, cut and moved/copied as usual for any text
  846. region. The regions are automatically renumbered internally. For those (like
  847. me) used to the ARMBE way of moving regions, there is a natural replacement.
  848. For example suppose you wish to move lines 10-50, to before line 100. In the
  849. ARMBE you would do:
  850.  
  851.   Move to line 10, cM cM, move to line 50, cM cM, move to line 100, cB, f12
  852.   
  853. In Zap you do:
  854.  
  855.   Move to line 10, cCOPY, move to line 60, ESCAPE, move to line 100, cV
  856.  
  857. Goto's are automatically updated. For example copy the lines 10 and 20 below
  858. several times in a basic program.
  859.  
  860.     10 PRINT "HELLO"
  861.     20 GOTO 10
  862.     
  863. Shift-F8 renumbers any program in steps of 10. Please note that line numbers
  864. are not stored in the undo buffer as this would be a waste of space. Thus
  865. after multiple undo's, the line numbers may get out of order. This can be
  866. rectified by Shift-F8. Basic programs can be appended by simply dropping them
  867. into the window.
  868.     
  869. C.3 Testing BASIC programs
  870. --------------------------
  871.  
  872. Zap provides a number of functions to test out basic programs while they are
  873. being edited. The first 3 start up a new BASIC task and ram transfers your
  874. program to the new task, loading it a PAGE:
  875.     
  876.  scB    This drops you into basic with your program loaded at PAGE.
  877.  scU    This acts as cB and then Runs the program.
  878.  scF    This acts as cU but automatically quits BASIC when finished.
  879.  
  880. The other two commands save the program first, and then run them from disc.
  881. These are of course slower:
  882.  
  883.  scC    This acts as cU but saves the program first and chains it from disc.
  884.  scE    This acts as cF but saves the program first and chains it from disc.
  885.  
  886. Zap calculates the amount of room needed to run the program as the maximum
  887. of: 1) Next slot size 2) Program size+16k 3) Program size * 1.5.
  888.  
  889. C.4 The cln_Backward error (trouble shooting)
  890. ---------------------------------------------
  891.  
  892. Occasionally, while editing Basic programs in the tokenised BASIC mode, you
  893. may get an error 'cln_Backward'. This essentially means that the BASIC
  894. program has become corrupted in some manner and it can't redraw the screen -
  895. usually the line numbers have got out of sync.
  896.  
  897. If you get this error then do not panic! The easiest way to save your program
  898. is to switch immediately to text mode (scF1) before doing anything else. Save
  899. it as a text file (if you wish), move to the top of the file and then switch
  900. back to BASIC mode (via scF6) renumber and then save the program. You may get
  901. the impression that an infinite sequence of errors occurs, so that you
  902. cannot switch to text mode. This is not the case, it's just that the window
  903. is not redrawn properly so the error box stays on the screen even after you
  904. have cancelled it - see if the OK icon gets highlighted when the mouse passes
  905. over it.
  906.  
  907. I have not yet tracked down all the possible causes of this error yet. The
  908. most common is selecting regions via the mouse using 'Adjust'. It is much
  909. better to use the keyboard selection (via cCopy).
  910.  
  911. *************************************************************************
  912. * Section D:    Individual mode help                    *
  913. *************************************************************************
  914.  
  915. Zap can handle up to 256 text processing modes. I have currently allocated
  916. space for 16. For details on how to write your own mode see the 'Docs'
  917. directory. The currently defined modes are described below. Additional help
  918. is given in the 'HelpData' file.
  919.  
  920. D.0 Text Mode
  921. -------------
  922.  
  923. This is a basic text editing mode. Most of the functions associated with this
  924. mode are detailed elsewhere. See the 'Helpdata' file for a detailed listing
  925. of menu options. To insert control characters in the text it is easiest to
  926. switch temporarily to byte mode. The character &09 in a text file is taken to
  927. denote a tab to next column of 8. You may change this character and the way
  928. it is displayed from the display menu. Tab action may be changed by the
  929. 'Misc.Tabs' menu.
  930.  
  931. D.1 Byte Mode
  932. -------------
  933.  
  934. This mode gives displays the file in hex bytes and is used for examining data
  935. or inserting control characters. The hex-entry flag (toggled by shift F3)
  936. controls this action. If it is off and you type '0B' then the letters '0' and
  937. 'B' will be inserted. If hex-entry is on (h in the title) then the byte &0B
  938. will be inserted. Use the overwrite mode (toggled via the insert key) to
  939. change the data without shifting the file.
  940.  
  941. D.2 Word Mode
  942. -------------
  943.  
  944. This is similar to byte mode except the data is shown in word form. Typing
  945. characters with hex-entry mode off has no effect, but typing with it on
  946. inserts the given word in hex.
  947.  
  948. D.3 Ascii Mode
  949. --------------
  950.  
  951. This mode displays data in ascii dump form. Letters typed are inserted as
  952. usual.
  953.  
  954. D.4 Code Mode
  955. -------------
  956.  
  957. This mode displays data in disassembled format with 1 instruction per line.
  958. Please note that in RISCOS 3, the debugger adds some extra information after
  959. some instructions, but some of this only appears if you disassemble
  960. sequentially. Eg TEQP R0,#0 followed by MOV R8,#0 gives the warning 'Not
  961. r8-r14'. However this may vanish if you are moving backwards up the file
  962. instead of forwards. This happens very rarely but it may cause confusion if
  963. you don't understand what's happening.
  964.  
  965. The four most useful keys in code mode are cI,Left,Right,Return. For example
  966. if you are at the start of a module then pressing cI will cause you to jump
  967. to the start offset of the module. If you are on an instruction 'BL
  968. &00012345' or 'ADR r0,&01822445' then pressing Right will jump to the
  969. indicated address. At any time, Left will move you back to your previous
  970. position. This jumping uses the marker buffer and can be done to any depth
  971. you require.
  972.  
  973. The RETURN key enables you to edit an instruction (via the ASSEMBLE command).
  974. When you press it, the minibuffer will be opened with the current instruction
  975. entered as default. You should then edit the instruction and press RETURN
  976. again for it to be assembled and written back. The assembling is done by the
  977. ZapBasic module which tokenises the instruction and then uses the BASIC
  978. assembler. Hence you may use the basic functions ASC,EQUD,ADR etc.
  979.  
  980. If the file is typed 'Module' then the first few offsets display the module
  981. entry point name rather than the instruction. 
  982.  
  983. D.5 BASIC Mode
  984. --------------
  985.  
  986. See sections C.1, C.2 and C.3 for details about how to use this mode.
  987.  
  988. A slight modification is made to the BASIC program on loading. The actual
  989. file format edited is  a number of lines of the form:
  990.  
  991.  xx yy zz "Tokenised line" &0D
  992.  
  993. Where xx yy zz is the line number in 3 byte text form as stored after a GOTO
  994. or GOSUB statement.
  995.  
  996. D.6 BASTXT Mode
  997. ---------------
  998.  
  999. This edits Basic files in detokenised form. See sections C.1 and C.3 for
  1000. details.
  1001.  
  1002. D.7 CMODE Mode
  1003. --------------
  1004.  
  1005. This mode provides facilities for editing C, TeX, and Gopher files including
  1006. bracket/dollar matching and function listing. The mode is written by Bryan
  1007. Scattergood. Please see the directory '3rdParty.BryanS' for details about
  1008. this mode.
  1009.  
  1010. D.8 C Mode
  1011. ----------
  1012.  
  1013. This provides a coloured C mode. See the directory '3rdParty.Ebourne' for
  1014. more details.
  1015.  
  1016. D.9 Assembler Mode
  1017. ------------------
  1018.  
  1019. This provides a coloured Acorn Assembler mode. See the directory
  1020. '3rdParty.Ebourne' for more details.
  1021.  
  1022. D.10 Pascal Mode
  1023. ----------------
  1024.  
  1025. See the directory '3rdParty.Ebourne' for more details.
  1026.  
  1027. D.11 THROWBACK Mode
  1028. -------------------
  1029.  
  1030. This mode handles the files generated by Zap's search to buffer, C throwback
  1031. and !Find info output. Double clicking on an item will jump to that item in
  1032. the source file. Shift double clicking will jump to the item and then kill
  1033. the throwback buffer. Clicking ADJUST on a line will remove the line from the
  1034. file. Treble clicking will move to the match and then bring the window to the
  1035. front of the window stack.
  1036.  
  1037. Also note that RETURN acts in the same way as double click and DELETE in the
  1038. same way as adjust if you move into the file.
  1039.  
  1040. D.12 Taskwindow Mode
  1041. --------------------
  1042.  
  1043. This mode handles task windows. To create a task window use the
  1044. 'Create.Taskwindow' menu option or press ctrl-F12. At any time, changing mode
  1045. to TEXT will suspend the task, and changing mode back to TASKWINDOW will
  1046. resume it. The taskwindow output supports the COPY key and the following VDU
  1047. actions:
  1048.  
  1049.     07 CTRL G    Bell.
  1050.     08 CTRL H    Move back one character.
  1051.     09 CTRL I    Move forward one character.
  1052.     10 CTRL J    Move down a line.
  1053.     11 CTRL K    Move up a line.
  1054.     12 CTRL L    Clear text window.
  1055.     13 CTRL M    Move to line start.
  1056.     22 CTRL V    Change mode.
  1057.     26 CTRL Z    Restore text window.
  1058.     28        Define text window.
  1059.     30        Home cursor.
  1060.     31        Move to x,y (TAB).
  1061.     
  1062. If you use Olly Betts' wonderful 'Line Editor' module then you'll find it
  1063. works within a Zap taskwindow. See the 3rdParty.Lineeditor directory for the
  1064. latest version. Mode changes are reflected by changing the width and height
  1065. of the window.
  1066.  
  1067. In general control-letter keys are passed on to the task window and function
  1068. keys are not. The following commands (usually bound to the bracketed keys)
  1069. are never passed on: Copy (Copy) Copysel (^C) Movesel (^V) Paste (^Y)
  1070. Clearsel (^Z) Quote (^Q). You can use ^C to copy commands to the active
  1071. task. If you want to send a control key or function key to the taskwindow
  1072. (which is not normally passed on) then this can be done by quoting it with
  1073. CTRL-Q. For example, CTRL-Q F1 will cause function key F1 to be expanded in
  1074. the taskwindow.
  1075.  
  1076. D.13-D.31 These modes are reserved
  1077. ----------------------------------
  1078.  
  1079. *************************************************************************
  1080. * Section E:    Search and Replace                    *
  1081. *************************************************************************
  1082.  
  1083. E.1 The Search window
  1084. ---------------------
  1085.  
  1086. Zap has quite a powerful search facility which is based loosely on emacs
  1087. search, allowing 'OR' constructs and character ranges. The search window can
  1088. created by pressing F4 or F7 or using the 'file' menu. Pressing F4 will
  1089. ensure that search matches are jumped to, whereas pressing F7 will cause all
  1090. matches to be placed in a separate throwback buffer. Double clicking on a
  1091. match in the buffer then jumps to the match. See section D.11.
  1092.  
  1093. The first column of the search window selects various search options. These
  1094. differ from earlier versions of Zap.
  1095.  
  1096. 'Raw search' - If this option is ON then the whole file will be treated as a
  1097. single line of text and searched accordingly. Thus \< will match the start of
  1098. the file only and \> the end of the file. A search will produce the same
  1099. result regardless of the mode a file is in.  If this option is OFF then the
  1100. file is searched in lines. This means that \< matches the start of a line and
  1101. that you cannot match across lines. In Basic mode the lines are detokenised
  1102. so that you can match PRINT and substrings of it. In Code mode the lines are
  1103. disassembled so that you can match substrings of instructions.
  1104.  
  1105. 'Case sensitive' - If this option is ON then strings of letters will only
  1106. match if their case agrees. If it is OFF then strings will match regardless
  1107. of case.
  1108.  
  1109. 'Use macros' -  In order that the user may have any search syntax he/she
  1110. chooses, I have adopted the following approach: 1. All wildcards/commands
  1111. begin with a '\' as listed below. 2. The user may define up to 16 macros
  1112. (aliases) in terms of these commands. 3. When the search string is entered,
  1113. all the user's macros are substituted before the search takes place. The
  1114. macros may be examined and altered by clicking on the 'Show Macros' button.
  1115. If this option is switched OFF then the macros are no longer substituted when
  1116. the search string is entered. The default macro definitions are stored in the
  1117. 'Keys' file and may be altered there. (For example; I have * as a standard
  1118. macro for \.\*. Thus if I typed in a*b, the string would be converted to
  1119. a\.\*b. However a\*b would remain as a\*b as the * follows a \ and is thus
  1120. treated as a command.)
  1121.  
  1122. '\' commands - If this option is switched OFF then \ will match the character
  1123. \ and not introduce a command (like \10). Hence, none of the commands below
  1124. will work.
  1125.  
  1126. The second column selects where the search should start and the direction of
  1127. the search. You may start at the beginning of the text or forwards/backwards
  1128. from the current cursor position, or search through all files (forwards from
  1129. the start of the first file in the stack).
  1130.  
  1131. The third column selects the output. If the 'to Window' option is OFF
  1132. (F4) then the cursor will be moved to the first match and subsequent matches
  1133. may be got by sF7 (Next match) and scF7 (Previous match) as in the Basic
  1134. Editor. A beep will sound if there are no more matches and the cursor will
  1135. not move. If the option is ON (F7) then all matches are placed in a new
  1136. (text) file. Double clicking on entries in this text file cause the cursor to
  1137. be moved to the corresponding match.
  1138.  
  1139. All these options can be toggled by using ctrl-letter keys where 'letter' is
  1140. the first capitalised letter of the option or ctrl-\ in the case of \
  1141. commands.
  1142.  
  1143. The table below details all the escape characters and commands. In it I will
  1144. use 'x' to stand for any ascii character unless otherwise mentioned.
  1145.  
  1146. x    Matches character 'x' (according to case sensitivity).
  1147. \x    Matches 'x' case sensitively, unless \x mentioned below.
  1148. `x    Matches 'x' only (without any replacement of macros).
  1149. \( \)    Act as brackets for nesting expressions.
  1150. \{ \}    Act as the normal brackets above, but may be referred
  1151.     to in the replace string during a search and replace. See E.2.
  1152. \#    Matches any character. Eg a\#d matches 'and','aad' but not 'ad'.
  1153. \.    Matches any character except the return character.
  1154. \*    Matches any number of the previous expression. Eg fo\* matches
  1155.     'f','fo','foo' etc. and \(and\)\* matches '','and','andand' etc.
  1156. \%    Matches the most number of repetitions of the previous expression.
  1157.     Thus \[0-9]\% matches '1' in '1pt' and the '395' in 'ab395rty'.
  1158. \|    Matches one expression OR another. Eg hello\|goodbye\|fred.
  1159.     Eg \(a\|b\)\* matches 'abababa','abbba' etc.
  1160. \[..]    Matches a range of characters. Eg \[a-zA-Z%] matches any letter or
  1161.     a '%'. If a '^' is given after the opening bracket then
  1162.     it acts as a NOT. Thus \[^abc] matches any character except a,b,c.
  1163. \<    Matches null string at line start (and file start).
  1164. \>    Matches null string at line end.
  1165. \+    Turns on case sensitivity for the following letters ONLY. It's
  1166.     effect stops at the next wildcard/bracket/command. It doesn't
  1167.     affect nested/bracketed statements - this will be improved.
  1168.     Eg \+Fred\|Bill matches Fred case sensitively but not Bill.
  1169. \-    As above, but turns off case sensitivity.
  1170. \\    Matches a '\'.
  1171. \ddd    Where d is any decimal digit matches that number.
  1172.     Eg '\0alf' matches byte 0,'alf' and \233 matches byte 233.
  1173.     Please note that \999 matches byte 99 followed by '9' as 999>255.
  1174. \&hh    As above but matches the hex byte hh when h are valid hex chars.
  1175. \A-\Z    Match ctrl A to ctrl Z.
  1176. \a    Matches alert (7)
  1177. \b    Matches backspace (8)
  1178. \f    Matches a form feed (12)
  1179. \hdd... Where d's are hex digits. Match the given word (32 bit number).
  1180. \n    Matches a new line (10)
  1181. \o    Matches any character except a '.' (useful for matching filenames).
  1182. \r    Matches a return (13)
  1183. \t    Matches a tab (9)
  1184. \v    Matches a vertical tab (11)
  1185. \wdd... Where d's are decimal digits. Match the given word (32 bit number).
  1186. \xhh    Matches hex numbers as above (where 'x' is the letter 'x').
  1187.  
  1188. In the examples below, the default macros are assumed. Please note that you
  1189. may macro the macros! Eg, you could define '(' to be '\(' and '\( to be '('
  1190. if you wished.
  1191.  
  1192. Examples:
  1193.  
  1194.  cat\|mat        Matches cat or mat.
  1195.  re*ment        Matches any occurrence of 're' then 'ment' on a line.
  1196.  SWI                Matches any SWI (in code mode).
  1197.  LDR\|STR        Matches any load or store instruction.
  1198.  R6            Matches any instruction using R6.
  1199.  BL*&0000A95C        Matches any call to &0000A95C.
  1200.  \&0A            Matches the byte &0A.
  1201.  \<fred            Matches fred, but only at the start of a line.
  1202.  main`(            Matches 'main('
  1203.  \d\%            Matches any number (where \d is macroed as \[0-9]).
  1204.  
  1205. Hints:
  1206.  
  1207. The search will be MUCH faster if you give a definite first character to
  1208. start with. Eg 'a\(nd\|pple\)' will be a lot faster than 'and\|apple'.
  1209. If the search takes longer than 1/3 second, then an hourglass will come up
  1210. displaying the position in the file as a percentage underneath. You may stop
  1211. the search by pressing Escape, and the partial results will be displayed if
  1212. you are using 'Search to buffer'.
  1213.  
  1214. E.2 The Replace window
  1215. ----------------------
  1216.  
  1217. A Search and Replace window can be created by pressing shift-F4 or from the
  1218. 'file' menu. The first two columns are as for the Search window. The third
  1219. column selects either selective or global replace.
  1220.  
  1221. For a selective replace (the global option OFF), each match will be
  1222. highlighted and a 'Replace ?' window will appear. Press 'R' to replace that
  1223. match and move onto the next match. Press 'S' to skip to the next match
  1224. without replacement. Press 'T' or 'E' to replace all matches from this point
  1225. (inclusive) to the end of the file. Press 'C' or ESCAPE to stop the selective
  1226. replace.
  1227.  
  1228. The format of the search string is described in section E.2. In the replace
  1229. string you may also use the following control sequences:
  1230.  
  1231. &n    Replace with the n'th \{,\} expression in the search string (n<10).
  1232. &&    replace with an '&'
  1233.  
  1234. If you wish to include parts of the match string in the replacement string
  1235. then you must surround the relevant sections in the search string with \{,\}
  1236. type brackets.
  1237.  
  1238. Examples:
  1239.  
  1240.  Search string:    Replace string:    Action:
  1241.  
  1242.  'cat'        ''        Removes all occurrences of 'cat'
  1243.  '\{cat\}'    '&1s'        Replaces 'cat' with 'cats' preserving case.
  1244.  'time=\{\#\}'    'time is &1'    Replaces 'time=58' with 'time is 58' etc.
  1245.  
  1246. To convert spaces between columns of figures in a table into tab characters
  1247. make the find string '\{\d\}  \*' and the replace string '&1\9'. Another way
  1248. to do this is replace '\{\d\} \%' with '&1\9'.
  1249.  
  1250. E.3 Keyboard (incremental/interactive) search
  1251. ---------------------------------------------
  1252.  
  1253. Incremental search is activated by pressing ctrl-S (Search forward) or ctrl-R
  1254. (Reverse search). When you do this a minibuffer will be opened for you to
  1255. type the search string into. As you type the search string, Zap will
  1256. search through the text placing the cursor at the end of the next match.
  1257. If there is no match then Zap will beep and print "(fail)". You may use the
  1258. DELETE key to remove characters from the search string.
  1259.  
  1260. To halt the search at the current position, press Escape or Return. If you
  1261. press an arrow or function key then the search will be halted and the key
  1262. then acted upon. Alternatively, pressing cG (Cancel) will cause the search to
  1263. be cancelled and the cursor returned to its initial position. This setup
  1264. should be familiar to users of Emacs.
  1265.  
  1266. Pressing ctrl-S or ctrl-R whilst in search mode will move you to the
  1267. next/previous matches. If the search string was empty then the previous
  1268. search string will be placed in the buffer.
  1269.  
  1270. Macros are turned off during the search so ('s etc act as normal. However,
  1271. \( and all other \-starting commands will still work so you must type \\
  1272. to search for a \.
  1273.  
  1274. *************************************************************************
  1275. * Section F:    Other features                        *
  1276. *************************************************************************
  1277.  
  1278. F.1 Learning key sequences
  1279. --------------------------
  1280.  
  1281. This feature of Zap is very simple to use, and very useful. To start
  1282. 'learning' a key sequence, simply press ctrl-L. Type the sequence you wish to
  1283. learn and then press ctrl-L again. Press F1 to execute the learnt sequence.
  1284.  
  1285. Note firstly that Zap will beep after every keypress you make to remind you
  1286. that it is being stored. Secondly note that the ESCAPE key will NOT stop the
  1287. learning process. Only ctrl-L will stop it. Thus you can learn sequences
  1288. which use incremental search, or keyboard selection of regions. Both these
  1289. actions involve the Escape key.
  1290.  
  1291. Once you have learnt a sequence, you may 'bind' that sequence to a key so
  1292. that pressing that key in future causes the same series of actions to take
  1293. place. To do this press CTRL F8 and then press the key you want to bind the
  1294. sequence to (or Escape if it was a mistake - Escape won't be bound).
  1295.  
  1296. The learn feature has many uses:
  1297.  
  1298. Example 1:
  1299.  
  1300. Suppose you wanted to insert a tab at the beginning of a group of lines. One
  1301. way would be to use the indent region option. Another way however would be to
  1302. learn the sequence: TAB,DOWN,CLEFT and then press F1 a number of times.
  1303.  
  1304. Example 2:
  1305.  
  1306. Suppose you wanted to go to the next match of 'cat' and switch the case of
  1307. the letters. You could learn the sequence:
  1308.  
  1309.  ctrl-S C A T ESCAPE LEFT LEFT LEFT scS scS scS
  1310.  
  1311. and then press F1 a number of times.
  1312.  
  1313. Exercise (for the reader):
  1314.  
  1315. When editing this !Help file I decided to switch the columns labelled 'Key:'
  1316. and 'Command:' around in section A.1. I did this by learning a key sequence
  1317. and then I only had to press F1 once for each line. What was the sequence?
  1318. (no prizes unfortunately).
  1319.  
  1320. F.2 Tabs and indenting
  1321. ----------------------
  1322.  
  1323. The standard tab character is taken to be &09. You may alter this from the
  1324. 'Display.Tabs' menu. This menu also allows you to alter the appearance of
  1325. Tabs. The menu 'Misc.Tab mode' controls how tabs are entered when you press
  1326. the TAB key. In 'Unix' mode the character &09 is inserted. In '!Edit' mode,
  1327. the cursor moves to the column which starts the next word on the above line.
  1328. In coltab mode, the cursor moves forward 'n' characters where 'n' is the
  1329. current coltab width. In the latter two, as many tab characters as possible
  1330. are inserted. If you wish spaces only to be inserted, then tick the 'as
  1331. spaces' menu option. Use shift-TAB to switch between 'Unix' and '!Edit' tab
  1332. modes.
  1333.  
  1334. To indent a region, first select it and the use the 'Selection.Indent' menu
  1335. option (or Ctrl J). Type 'n' to indent by n spaces, '-n' to remove n spaces,
  1336. or type a string to indent by that string. Use the command OUTDENT to
  1337. outdent the region. The region is outdented by the length of the current
  1338. indent string (thus a negative indent string will cause outdent to indent
  1339. :-).
  1340.  
  1341. F.3 Fonts and font sizes
  1342. ------------------------
  1343.  
  1344. The font used in a Zap window is determined by the 'Display.Font' menu. There
  1345. are basically 4 options. You may either have (1) a bitmap font drawn by Zap
  1346. (2) The system font drawn by the operating system (3) Anti-aliased fonts
  1347. drawn by Zap (4) Anti-aliased fonts drawn by the OS.
  1348.  
  1349. (1) is the fastest and recommended for normal use. A range of bitmap fonts
  1350. are provided.
  1351.  
  1352. (3) is still at the experimental stage and contains a number of bugettes.
  1353.  
  1354. (4) is very slow.
  1355.  
  1356. The configured font is changed in the KEYS file and NOT from the options
  1357. menu.
  1358.  
  1359. To configure the anti-aliased font name and size, change variables &302 and
  1360. &304 in the keys file. You may also use variables &305/306/310/311 to shave
  1361. off surplus spacing around font characters. Fonts are monospaced.
  1362.  
  1363. When using the FAST FONT option, it should be noted that the font is only
  1364. cached in one set of anti aliased colours. These are taken to be the default
  1365. colours for text mode foreground and background. All other colours are drawn,
  1366. but not anti-aliased.
  1367.  
  1368. F.4 Universal arguments.
  1369. ------------------------
  1370.  
  1371. The universal argument feature enables you to execute a keypress an arbitrary
  1372. number of times. Suppose for example you wanted to insert 100 spaces. The
  1373. quick way to do this is to type:
  1374.  
  1375.     CTRL-U 100 SPACE
  1376.     
  1377. In general you type CTRL-U then the number of times you want the key to be
  1378. executed, then press Return, then press the key to execute. The 'pressing
  1379. Return' step can be omitted if the key you want to repeat is not delete or a
  1380. digit or another valid key for editing the number you are typing (as in the
  1381. example above).
  1382.  
  1383. F.5 The minibuffer
  1384. ------------------
  1385.  
  1386. Some Zap commands can take parameters. In order that these parameters can
  1387. be entered at run time, a minibuffer is provided. If you type a command into
  1388. the 'keys' file without specifying its parameter then, when you press that
  1389. key, the minibuffer opens. You should type in the command argument and then
  1390. press RETURN. Several examples keys are cESC,cS,cR,cW,F2.
  1391.  
  1392. Several control keys have default meanings in the minibuffer. These can not
  1393. at the moment be reconfigured, but are compatible with the Emacs minibuffer
  1394. keys:
  1395.  
  1396.     cA / cLeft    Move to start of line
  1397.     cB / Left    Move back a character
  1398.     cD / sDelete    Delete the next character
  1399.     cE / cRight    Move to end of line
  1400.     cF / Right    Move forward a character
  1401.     cG / Escape    Quit the minibuffer
  1402.     cK        Delete to end of line
  1403.     cU        Clear minibuffer
  1404.     TAB        Complete key (eg after F2, TAB will complete
  1405.             filenames)
  1406.     RETURN        Execute the command.
  1407.     
  1408.     If you have the Lineeditor module loaded (version >= 2.67)
  1409.     
  1410.     Up / sUp    Recall line
  1411.     Down / sDown    Next line
  1412.     cUp        First line in recall buffer
  1413.     cDown        Last line in recall buffer
  1414.  
  1415. These keys can be redefined by commands, but should remain as consistent as
  1416. possible with the above.
  1417.  
  1418. *************************************************************************
  1419. * Section G:    How to find out more                    *
  1420. *************************************************************************
  1421.  
  1422. G.1 Other help files
  1423. --------------------
  1424.  
  1425. The 'Helpdata' file contains help for all the leaf windows, main windows, and
  1426. commands. You can view this by using Acorn's !Help application, or just by
  1427. loading the text file. On RISC OS 2/3.0 you cannot get help on the menu
  1428. entries, only the windows (but you can just read the file directly).
  1429.  
  1430. For those interested in writing an extension mode, or adding new commands, or
  1431. Zap's internal workings, please look in the Docs directory. You should start
  1432. with the file called ReadMe. This directory also contains a Zap keystrip in
  1433. the form of a Draw file.
  1434.  
  1435. Please see the file 'Changes' for my future plans for Zap.
  1436.  
  1437. G.2 Obtaining future versions of Zap
  1438. ------------------------------------
  1439.  
  1440. I will be sending any future versions (>1) of Zap to:
  1441.  
  1442. 1) Hensa: e-mail: archive-server@micros.hensa.ac.uk (send message 'help')
  1443.       ftp   : micros.hensa.ac.uk (IP 148.88.8.84)
  1444.       (outside office hours only for those not on Janet)
  1445.  
  1446. 2) The Archimedes Public Domain Library (run by David Holden):
  1447.    39 Knighton Park Road
  1448.    Sydenham
  1449.    London
  1450.    SE26 5RN
  1451.    
  1452. Please look at the 'Changes' file for the anticipated release date.
  1453.  
  1454. G.3 Contacting me with suggestions/bugs
  1455. ---------------------------------------
  1456.  
  1457. Suggestions and bug reports are welcome. See the Copyright file for my
  1458. address (E-Mail preferred). Before sending suggestions please read the
  1459. 'Changes' file. If you find a bug then please give me as many details as
  1460. possible as to the circumstances that cause it - try and get it repeatable.
  1461. If you have a comment on a Zap extension mode not written by me then please
  1462. write to the author (see 3rdParty.ReadMe).
  1463.  
  1464. I hope you find Zap a useful program.
  1465.  
  1466. Dominic Symes
  1467. May 1995
  1468.